Skip to main content
Expert Talk
Amakomaya — Aamako Maya Apps Pvt. Ltd.

Architecture Decision Record Template

One decision, one file, numbered sequentially, never deleted. Background and worked examples are in architecture decision records.

The template​

# ADR-NNNN: <Decision, stated as a sentence in the active voice>

- **Status:** Proposed | Accepted | Rejected | Deprecated | Superseded
- **Date:** YYYY-MM-DD
- **Deciders:** <names or body>
- **Consulted:** <who was asked>
- **Supersedes:** ADR-NNNN | —
- **Superseded by:** ADR-NNNN | —

## Context

What is true that forces a decision now. Constraints, data, deadlines, legal
requirements, existing commitments. Written so that someone in three years can
tell whether these conditions still hold.

State the facts, not the preferred conclusion.

## Options considered

### Option 1: <name>
What it is. Consequences, good and bad.

### Option 2: <name>
What it is. Consequences, good and bad.

### Option 3: <name>
What it is. Consequences, good and bad.

Give each option a fair account. An ADR listing one real option and two straw
men records nothing useful.

## Decision

What was chosen, in one sentence, in the active voice.

"We will route all inter-system traffic through the interoperability layer."
Not "it was decided that traffic should generally be routed…".

## Rationale

Why this option, against the alternatives, given the context. Name the deciding
factor — usually one constraint dominates, and identifying it is what makes the
decision reviewable later.

## Consequences

What becomes easier. What becomes harder. What we are now committed to. What we
must build, staff or fund as a result.

Include the consequences you do not like.

## Implications

- **Security and privacy:**
- **Interoperability:**
- **Scalability and operations:**
- **Cost:**
- **Clinical safety:**

Complete every line. If one genuinely does not apply, write "none identified"
rather than deleting it — the deletion is indistinguishable from an oversight.

## Follow-up

- Actions arising, with owners
- Conditions that would trigger revisiting this decision
- Review date, if any

Conventions​

Numbering. Sequential, zero-padded (ADR-0007), never reused, never renumbered. The number is a citable address that appears in design documents, code comments and diagrams.

Filenames. NNNN-short-kebab-case-title.md, so the directory sorts correctly.

Location. Version control, alongside the code or in an architecture repository. Ideally in the same pull request as the change it describes.

Index. Maintain a table at the top of the directory:

| # | Title | Status | Date |
|---|-------|--------|------|
| 0001 | Use FHIR R4 as the exchange standard | Accepted | 2026-01-08 |
| 0002 | Adopt a separate health identifier | Accepted | 2026-01-15 |
| 0007 | Route all traffic through the interoperability layer | Accepted | 2026-01-20 |
| 0014 | Use deterministic matching for the client registry | Accepted | 2026-03-11 |

Superseding. When a decision changes, write a new ADR and mark both. Never edit the original beyond adding the Superseded by link. The old reasoning is the record of why the constraint mattered.

Status transitions. Proposed while under review; Accepted once decided; Rejected if not adopted — keep rejected ADRs, they prevent the same proposal returning every year; Deprecated when no longer relevant; Superseded when replaced.

Length​

One to two pages. Longer ADRs do not get written, and unwritten decisions are the problem this practice exists to solve.

If the context genuinely needs more, put the detail in an appendix or a linked analysis document and keep the ADR itself short.

The ten to write first​

If a health architecture programme writes only ten ADRs, these are the ones — each is expensive to reverse and each is usually decided by accident:

  1. The authoritative patient identifier, and what happens when it is absent
  2. The matching strategy and who adjudicates
  3. The exchange pattern
  4. The exchange standard, version and upgrade policy
  5. Terminology bindings and who maintains the value sets
  6. The authorisation model
  7. The consent model, including break-glass
  8. Data residency and hosting, with the legal basis
  9. The offline strategy and conflict resolution
  10. What the analytics layer consumes
Last updated on